SX212 Modem Handler Technical Description This document describes the software that allows the Atari eight bit computer product line to use the SX212 modem. The information presented here is written for those with a good technical understanding of the Atari eight bit line. For information regarding the modem itself, please reference the SX212 Owner's Manual. Note that this document is formatted for 80 column output. General Description Communication with the modem is governed by a software modem handler that resides within the memory of the Atari computer. This handler is initially loaded from disk, but once in memory stays there until the computer power is turned off. The handler is known to the system as the "R:" device. The cassette motor line on the SIO bus controls communications with the modem. When the motor line is off, no communication is possible with the SX212. To enable IO to and from the modem, the handler turns the motor line on. The handler supports standard OS calls (OPEN, CLOSE, GET, PUT, STATUS) as well as special (XIO) calls to control baud rate, output parity, and translation. Input parity is not checked. These commands have been designed to be compatible with the RS232 (850) commands. Thus programs written for the 850 interface using a modem should operate correctly when using the SX212. Handler Functions OPEN An OPEN command may be executed before or after the configuration commands (XIO34, 36, 38) but must be issued before starting concurrent mode (XIO40). Set AUX1 to 13. AUX2 is ignored. If an OPEN command is issued through CIO, then the specified IOCB is linked to the R: (modem) handler. The open command causes the handler to zero the input and output buffer pointers, which sets the buffer lengths to zero. CLOSE The CLOSE command sends any bytes remaining in the output buffer to the modem and then stops concurrent mode by turning off the cassette motor line on the SIO. Any characters received from the modem are ignored. The SIO bus is returned to its normal mode of operation, and associated interrupt vectors are restored. If the CLOSE command is issued through CIO, then the specified IOCB is unhooked from the modem handler. At this point the SIO bus is available for data transfer to other peripherals. GET Issuing a GET command will cause the handler to obtain a character from the input buffer and possibly translate it if so specified by a previous configuration command (XIO38). When finished making any changes to the character, the handler will return to the calling program with the character in the accumulator. If no characters are in the input buffer when the GET call is made, the handler will wait for one to be received from the modem. Once the character arrives, the above sequence occurs. If the handler is waiting for a character from the modem and the user presses the BREAK key, the GET operation will be terminated and the handler will return to the calling program with a status of 128. Get must be executed while concurrent mode is on, otherwise error 154 will be generated and no character will be returned. PUT Issuing a PUT command will cause the handler to possibly translate the character and adjust parity for it as determined by a previous configure command (XIO38). The handler will then check the character count in the output buffer. If full, the handler will wait until room is available, then place the character in the buffer. If the buffer is only partially full, then the character is immediately put in the buffer. If the buffer is empty, then the character is sent directly to the modem. Put must be executed while concurrent mode is on, otherwise error 154 will be generated and no character will be sent. STATUS The status command causes the handler to store information about the modem and handler into locations 746 through 749 (Hex 2EA to 2ED). Location 746 gets communications error information as described below. Location 748 is always set to 0. If concurrent mode is on, then location 747 will be the count of characters in the input buffer, and location 749 will be the count of characters in the output buffer. If concurrent mode is off, then 747 will contain the status of the carrier signal and communication speed, and 749 will be 0. The overflow bit in location 746 is cleared after each status call. Location Bits Data Meaning 746 $2EA 7-0 0 No errors 7 1 Received data framing error - serial data is out of phase or garbled. 6 1 Received data byte overrun error - computer did not respond in time to incoming data. 4 1 Received data buffer overflow error - user program did not respond in time to incoming data. This bit cleared each status call. 747 $2EB 7-4 1 Always 1 (850 compatibility) 3,2 11 carrier ON, ON since previous status call 10 carrier ON, not always ON since previous call 01 carrier OFF, not always OFF since previous 00 carrier OFF, OFF since previous 1 1 Hi speed (1200 baud) at modem 0 Lo speed (300 baud) at modem 0 1 Received data line is 1 0 Received data line is 0 SPECIAL COMMANDS XIO34 Force Modem Hangup - Clear DTR Since the DTR line cannot be manipulated directly (as in the 850) and thereby hangup the modem, this command uses a different approach to achieve the same goal. Its interface is the same as the 850 from a programming standpoint, so the command requirements are the same. Concurrent mode must be off, otherwise error 153 will be returned. AUX1 must be 128, otherwise the command will be ignored. AUX2 is ignored. The handler then makes the modem hangup by placing it in "local" mode (see SX212 manual) and then issuing an "ATH0" or "on hook" command. XIO36 Specify Speed - Set BAUD This command is used to set or change the modem communication speed. The two allowed speeds are 600 and 1200. The AUX1 byte of the command specifies the speed. Values 0 to 9 will set 300 baud, and values 10 to 15 will set 1200. The upper 4 bits of AUX1 are ignored. AUX2 is also ignored. XIO38 Specify Parity, Translate, and Won't Translate Character As a byte is prepared for output, it is first translated and then parity is generated. When a byte is received, it is just translated. Translation applies to both input and output. Translation can be one of three types: no translation, light, and heavy. No translation allows all 8 bits of data to pass to or from the modem. In both light and heavy translation modes, the ATASCII EOL (155) is converted to (on output) and from (on input) the ASCII CR (13). If the append line feed bit has been set, on output the EOL will be converted to a CR character followed by a line feed (LF) character. On input the high bit of each byte is cleared to zero. During output the high bit is set to zero. Light translation only makes the changes mentioned above. Heavy translation, however, adds two conditions. During output, characters having ASCII values below 32 decimal or above 124 will not be sent. During input, characters with ASCII values below 32 decimal or above 124 will be replaced with the wont translate character. AUX1 specifies translation, output parity, and line feed append. Bits Data Meaning 6 1 Append LF after CR (translated from EOL) 0 Do not append LF 5,4 11 Reserved 10 No translation 01 Heavy ATASCII/ASCII translation 00 Light ATASCII/ASCII translation 1,0 11 Set output parity bit to 1 10 Set output parity even 01 Set output parity odd 00 Do not change output parity bit AUX2 is ASCII value of the won't translate (replacement) character for heavy translation on input. XIO40 Concurrent Mode On This command must be executed before characters can be sent to or received from the modem by the application. Once this command has been given, no other peripherals on the serial bus can be accessed. To communicate with other peripherals, the CLOSE command must be issued. This command causes the handler to turn on the motor control line and then modify the SIO bus controls to communicate with the modem at either 600 or 1200 baud. The baud rate is set by the AUX1 byte in the XIO36 command. Errors Generated by the Handler 128 - If the user presses the BREAK key while the handler is waiting for characters from the modem, the operation will be terminated and error 128 will be returned in the status byte. 153 - This error means that concurrent mode must be turned off (by a CLOSE command) before issuing the XIO34 command. 154 - When this error is returned, either a GET or PUT command was executed without first turning on concurrent mode. Internal Operation of Handler The handler allocates two buffers for transmitted and received data. Each buffer is 256 bytes long and is circular in nature. As data is put into the buffer each byte is stored at one memory address above the previous. When the end of the buffer is reached, the next byte is placed at the beginning of the buffer, and successive bytes follow it. At the same time data will be removed from the buffer in the same manner. The handler receives characters from the modem (when concurrent mode is on) and places them in the input buffer. This buffer is circular, so that as characters are obtained from the handler, the end of the buffer moves into space previously occupied by incoming characters. If at any time the end of the buffer meets the beginning, the overflow bit (4) of the internal status byte will be set. A status call writes this byte to location 746. The handler sends characters to the modem from its output buffer until empty. This process is interrupt-driven via the POKEY chip. The handler initiates the first byte of output by storing the byte in the POKEY serial output register. Should the speed of the modem change (1200 to 300, or 300 to 1200) the handler will sense the change and set the corresponding bit in its internal status byte. At a status call the internal status byte is transferred to location 746. The handler can also sense changes in the carrier signal. These can also be monitored by the status call. Booting Sequence and Initialization of Handler The handler loads as follows: A DOS disk containing the handler must be in drive 1. The computer is powered on, causing a disk boot. The DOS is loaded in and initialized. The DOS init code locates the file named AUTORUN.SYS and loads it. The modem handler must be named AUTORUN.SYS to be loaded at boot time. The handler file is loaded into RAM at address $3000 and continues upward approximately 1.6K bytes. The file consists of a relocater portion followed by the actual modem handler. After the file is in memory, DOS causes the init code of the file to execute. This init code is the relocater which uses a variable in the OS called MEMLO ($2E7,2E8) to find the first address of user (or non-system) RAM. MEMLO is then increased by the relocater to point to an address about 1.5K above its old value. This makes room for the handler portion, which is moved to that address space by the relocater. While the relocater is moving the handler to its proper location, it resolves all absolute address references within the handler code. Thus the handler code is originally on the disk file in a relocating format. After the handler has been moved, the relocater sets the DOSINI vector in the OS ($0C,$0D) to point to the handler init code, sets an address within the handler to point to the old DOSINI code, then jumps to the handler init code. The initialization code begins by installing (or replacing) the "R:" device code into the OS handler table. This will allow CIO calls to access the handler. The INTERRUPT and PROCEED vectors are then changed so the handler can monitor the SPEED and CARRIER lines from the modem. The serial IO interrupt vectors are copied for later use so the handler can deal with the SIO bus itself. Next, all the internal variables of the handler are cleared. At this point the handler determines the current status of the modem. This is done by setting the baud rate to 1200 and issuing an "ATS15?" command to the modem. The command is a request for the modem to return information about its operating characteristics. The modem can respond in one of three ways. First, the modem can respond with the information which the handler then copies into its internal status bytes. Second, the modem may not respond at all, in which case the handler assumes the modem is either unplugged or turned off. The handler programs an interrupt to occur when the modem comes back on line. Note that the time out interval for modem response is about 2 seconds. Third, the modem may respond, but with garbled data. In this case the handler assumes the current baud rate is wrong and switches to 300. It then retransmits the ATS15? command. Once the modem status has been established, the handler may issue one more command to the modem. If the carrier line is on, then the current init sequence was the result of either the computer power being cycled or the RESET button being pressed while the modem was still on line with another modem elsewhere. When the handler has determined that this has happened, it sends an "ATO" command which tells the modem to return to normal (or transparent) mode. The handler then exits. Messages from Handler to Modem "ATS15?" request contents of register S15 "ATO" go to transparent operation "ATH0" force hangup "+++" interrupt modem operation Handler File Format (Values in boxes are in HEX) AUTORUN.SYS File Format Relocatable Format of Handler +-------+ +----+ | FF,FF | DOS Load File flag +--| XX | Link byte to first relocate byte +-------+ | +----+ | 00,30 | Start Add = $3000 | : : Valid 6502 Code (non relocate) +-------+ | +----+ | LO,HI | End Address +->| XX | Add offset to this byte (hi byte) +-------+ +----+ : : Relocater Code +--| XX | Link byte to second relocate byte +-------+ | +----+ | LO,HI | Handler Length | : : Valid 6502 Code (non relocate) +-------+ | +----+ | 20 | JSR Instruction +->| XX | Add offset to this byte +-------+ for DOSINI set +----+ | LO,HI | by Relocater +--| 00 | Example Link of 0, following byte +-------+ | +----+ is high byte to relocate | 4C | JMP Instruction +->| XX | Add offset to this byte +-------+ to INIT code +----+ | LO,HI | set by Relocater +--| 80 | Special Case 80 means skip 127 +-------+ | +----+ data bytes, then treat byte 128 : : SX212 Handler | : : as the next link : : Code in +->+----+ : : Relocatable Format +--| XX | Link +-------+ | +----+ | E2,02 | INIT Vector | : : Valid 6502 Code +-------+ that DOS will | +----+ | E3,02 | use to execute +->| 00 | Dummy byte to Relocate +-------+ handler code at +----+ | 00,30 | this RUN address | FF | Special Case FF means end of +-------+ +----+ relocating section